feat(platform-objects,mcp): a member's agent finds a colleague through the read-only sys_user - #33180

Requested by Tesla · project thread

epic:#32897#1 · os-tesla · session_01L9qibzL1RvtJP7jM7QZJaF

Fixes #32641

Clause-②: yes (widening)
Metadata-protocol: none

维护者速读

• 改了什么：sys_user 声明了 enable.aiReadable: true。成员的 MCP 代理现在能用现有的 query_records / get_record 按邮箱或姓名找到同事、拿到用户 id，去填「负责人 / 审批人 / 员工」这类人员字段。没有新工具，任何写工具仍拒绝 sys_user。query_records 的说明和下发的 SKILL.md 教代理：按邮箱找唯一一个人；重名时用邮箱区分。
• 为什么改：你裁了 B（6844187236）：代理看到的和该成员在控制台人员选择器里看到的一样，同组织、只含通讯录字段；邮箱可见（6867150851）。
• 风险与回滚：代理拿到的字段＝控制台成员能读到的整行，减去 Admin 组：id、姓名、邮箱、邮箱已验证、两步验证开关、停用标记、头像、语言、上级、主业务单元、账号类型（人/AI）、责任人、来源、创建/更新时间。登录记录、锁定、封禁原因、登录手机号、AI 席位等 Admin 组字段不给，按它筛选也被拒；别的组织的用户查不到。这比 option B 原文「只有姓名/邮箱」宽，座位已就此问你（卡上 6867361507）；若你要只留 id/姓名/邮箱，需要新加一条只针对代理的屏蔽规则，那是另一个决定。回滚即撤本 PR。
• 先看：① packages/platform-objects/src/identity/sys-user.object.ts 的 aiReadable: true 与注释；② packages/qa/dogfood/test/colleague-lookup-over-mcp.dogfood.test.ts（端到端：找人、跨组织不可见、Admin 组被屏蔽、写被拒、填人员字段）；③ packages/mcp/src/skill-md.ts 新加的「People are sys_user records」一条。
• 两分钟验证：pnpm --filter @objectstack/dogfood exec vitest run test/colleague-lookup-over-mcp.dogfood.test.ts，预期 10 条全过。
• 需要你做的：回答座位的字段集问题（控制台同款 / 只留 id、姓名、邮箱）；在你回答前本 PR 不落地。

What changes

• packages/platform-objects/src/identity/sys-user.object.ts: enable.aiReadable: true (the mechanism PR feat(approvals,mcp): an approver's agent lists the approvals waiting on them over MCP #33117 landed, 3eac63a9). Both MCP bridges already attest it through isAiReadExposed, so the five read tools (list_objects, describe_object, query_records, get_record, aggregate_records) admit sys_user; the write tools keep the plain sys_* guard. No code change in the admission.
• No permission change. member_default already grants sys_user allowRead (default-permission-sets.ts, the sys_user object entry), scopes rows with sys_user_self + sys_user_org_members (id in current_user.org_user_ids), and withholds the Admin field group with identityAdminFieldSecurity('withhold'). Those are exactly the gates the console person picker (UserField → PeoplePicker → useRecordQuery, no field projection) is served through, so the agent's read and the picker's read are the same read.
• What an agent is told. query_records' description: "To fill a person field, find the colleague's id: objectName "sys_user", where {"email":"..."} for exactly one person, or {"name":{"$contains":"..."}}; names repeat, so tell people who share a name apart by email." The served SKILL.md (packages/mcp/src/skill-md.ts) gains a Conventions bullet saying the same, plus "ask your human which one if unsure", and its list_objects line no longer says every system object is hidden. The Console "Download skill" copy (ui/apps/console/src/pages/developer/objectstack-skill.ts) carries the same two edits, because skill-md.test.ts holds it byte-identical to the served render.
• Docs. content/docs/ai/connect-mcp.mdx (the default-exposure bullet names sys_user, what is served, that names repeat) and packages/mcp/README.md (the list_objects line names both declared objects).
• Changeset .changeset/32641-sys-user-ai-readable.md: @objectstack/platform-objects, @objectstack/mcp, @object-ui/console patch, both declaration lines, the served field list.

The served field set (measured, live row)

For a plain member, on a colleague's row, over MCP and at the HTTP data door alike: accountable_user_id, banned, created_at, email, email_verified, id, image, locale, manager_id, name, primary_business_unit_id, principal_kind, source, two_factor_enabled, updated_at. That is every declared field outside the Admin group; the dogfood pins it as "declared minus Admin group", read off the declaration, so a field moved into or out of the group moves the pin with it.

Tests

• packages/qa/dogfood/test/colleague-lookup-over-mcp.dogfood.test.ts (new, 10 tests). Real SecurityPlugin, real MCPServerPlugin, the live /mcp transport; no permission set in the file names sys_user (members hold the shipped baseline and an app set naming the app's one object). Fixture: a member, two colleagues who share one name, and a third user of that name moved into another organization (membership and sessions); synthetic Admin group values on one colleague. Armed controls: the group is non-empty and covers the fixture fields; the values are at rest; the outsider is in another organization and the name matches three rows at rest.
  • by name, the member finds exactly the two colleagues and tells them apart by email; $contains on a partial name, the same two; by email, exactly one id;
  • the outsider is invisible: by name, by email (empty), in the unfiltered list, by id (get_record refused, no email leaked), by count (n: 2);
  • the Admin group: not on the served row, not on a projection naming it, and a filter on failed_login_count is refused; control: the platform admin's get_record is served last_login_ip;
  • the agent's query_records and the member's GET /data/sys_user return the same ids and the same field set, which equals the declared non-Admin fields;
  • create_record, update_record (own row and a colleague's), delete_record, delete_records are each refused with the system-object sentence, and nothing changed at rest;
  • the query_records text names sys_user and email;
  • end to end: find by email, create_record on the app object with assignee = the found id, the stored row holds it.
• packages/platform-objects/src/identity/sys-user-ai-read.test.ts (new, 2): the declaration and isAiReadExposed; apiMethods unchanged.
• packages/mcp/src/skill-md.test.ts (+1 describe): the served skill's bullet names query_records, "email", $contains, "tell them apart by email", "read only"; the old "are hidden" claim is gone. The existing byte-identity pin holds the Console copy.
• packages/qa/dogfood/test/approval-read-over-mcp.dogfood.test.ts: its list_objects pin said sys_approval_request is the only listed sys_* object; it now lists sys_approval_request and sys_user.

Ablations

Each on a committed head with scripts/ablation-replace.mjs --hold, the package rebuilt, scripts/ablation-dist-preflight.mjs proving the mutation in dist/ before the run and gone after the restore, restore proved blob == HEAD and git status --porcelain empty.

A4's first try used a comment as the marker, which the bundler strips, so the preflight refused it and nothing ran; the second used an identifier. A2's first try used an anchor that occurs three times without --expect 3, so nothing was written and the run was void; it was rerun with --expect 3.

Acceptance notes

• The field-set fork is open. The ruling record 6844187236 says "exactly what that member sees in the console's person picker … directory fields only (plugin-security: an org member reading a colleague's sys_user row is served the Admin-group fields (last_login_ip/at, failed_login_count, locked_until, ban_*, phone_number) — and through sys_activity, their sign-in history #21237)"; option B's own text and triage's 6867150851 say "name/email only" / "no other sys_user field is visible". The existing gates serve the console set above (15 fields). Narrowing the agent to id/name/email needs a new agent-only mask that the console does not use. This PR builds the console reading and contains no such mask; the seat has put the question to the maintainer (6867361507). If the answer is id/name/email only, this comes back as a fork.
• Clause-② derivation. The five MCP read tools refused sys_user on main (A1 is that state, measured); after this PR they serve it. Widening only: no tool, schema, export or answer shape narrows.
• Metadata-protocol derivation. enable.aiReadable already exists (spec spec: a per-object, read-only AI exposure declaration so an agent can read a declared system object through the MCP record tools (#32442 read half) #32865); this declares a value on a platform object. No authorable key, value or type is added, narrowed or changed in meaning.
• Not in the file surface the claim names, changed as consequences: ui/apps/console/src/pages/developer/objectstack-skill.ts (held byte-identical to skill-md.ts by skill-md.test.ts) and packages/qa/dogfood/test/approval-read-over-mcp.dogfood.test.ts (its pin listed the sys_* set this PR grows).
• stdio. The stdio bridge answers aiReadExposed with the same isAiReadExposed, so a stdio host admits sys_user too; the row and field gates there are the sibling card's (mcp: stdio describe_object and the objects resource serve readonly: false for a stored expression field whose expression the caller's field mask hides, while the HTTP door answers true #33156 / MCP stdio get_record answers a missing or hidden id with uncoded error text, while the HTTP door answers RECORD_NOT_FOUND 404 #33030) scope and are not pinned here.
• Not touched: skills/** (Tier H). The served MCP skill is skill-md.ts, which carries the ruling-6867150851 sentence.
• Dogfood full battery: not run (no ! in the title, no (narrowing) arm); the two MCP dogfood files that read this surface ran, 20/20.

Verification

Local, on head 1e1c1561:

• pnpm --filter @objectstack/platform-objects test 122 files / 1957 tests passed; pnpm --filter @objectstack/mcp test (after merging main) 64 / 1141 passed.
• pnpm --filter @objectstack/dogfood exec vitest run --maxWorkers=2 test/colleague-lookup-over-mcp.dogfood.test.ts test/approval-read-over-mcp.dogfood.test.ts 2 files / 20 tests passed (after merging main).
• typecheck: platform-objects 0, mcp 0, dogfood 0 (the dogfood one at an 8 GiB heap: the default 4 GiB OOMs, exit 134).
• Derived gates (node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, 100 commands, each with stdin closed) and pnpm lint: all exit 0. Three exited 3 (PREREQUISITE NOT MET, nothing measured) on the first pass and exit 0 on a rerun after the precondition was met: check:dual-build-cjs-loads and check:skill-examples (packages without dist/, built), check-plugin-teardown-shape --self-test (its pinned fixture commit, fetched into this shallow clone). --ran reconciliation: 100 derived, 100 run, 0 NOT-MEASURED (a derived zero: every line carries its exit code); pnpm lint recorded outside the derivation.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

Generated by Claude Code